We might just consider backing out c47e854, which introduced this property in the last release. What is the intention of it in CocoaPods, and how do other projects use it?

Also of note: Mapbox.h contains our "public" headers, which are classes that we endorse, document, and support, as opposed to all of the headers that came from upstream.

Reverting c47e854 has the same effect as this PR (e.g., including all headers), except that it will be less obvious where the headers are coming from.

The official intention is:

These are the headers that will be exposed to the user’s project and from which documentation will be generated. If no public headers are specified then all the headers are considered public.

In theory this sounds fine: exclude headers without public API. But our SDK won't compile without these "private" headers. Frankly, I don't understand CocoaPod's implementation/mindset here.

Most other projects use a similar wildcard to what I'm proposing in this PR. AFNetworking, for example: s.public_header_files = 'AFNetworking/*.h'

These are the headers that will be exposed to the user’s project and from which documentation will be generated.

The problem here is CocoaPods trying to be "helpful" and auto-generate documentation that goes here:

http://cocoadocs.org/docsets/Mapbox-iOS-SDK/1.6.1/

In past, I've lobbied (successfully) to get a directive that links to an external place (like our hosted docs) because CocoaDocs was both putting up docs for classes we didn't want up as well as docking us points for not having all classes documented.

It seems though that CocoaDocs is still generating a page for us, even if it's not linked in the summary. So our use of public_header_files is working.

I'm worried the wildcard will mess up that page again, and people who get there will get an incomplete / inaccurate picture of the toolset.

The cocoapods-headers-yupyup branch adds the header.dir property to the podspec, which is: "The directory where to store the headers files so they don't break includes."

That's all it says. Setting header.dir fixes our compilation errors, but only once you pod update after you've just pod install'd.

My inclination here is to go with the wildcard (or reversion) — the library compiling successfully should be our main goal. That CocoaPods is generating docs for us that are wrong and that we can't correct is regrettable, but the lessor evil in this case.

I'll post on the CocoaPods repo about these issues and see what comes of it.

Sounds good @friedbunny — that seems to be the right call. We do link out properly to our own docs page, so let's just go with that and not spend too many cycles on hiding/removing the CocoaDocs version since we'll deprecate before much longer anyway.